Hms standalone rest server with Spring Boot by difin · Pull Request #6327 · apache/hive

difin · 2026-02-19T15:54:20Z

What changes were proposed in this pull request?

The Standalone REST Catalog Server is reimplemented to use Spring Boot instead of plain Java:

Server framework – Uses Spring Boot with an embedded Jetty server instead of raw servlet wiring.
Health checks – Adds Actuator liveness and readiness probes; readiness verifies HMS connectivity via Thrift.
Observability – Exposes Prometheus metrics for Kubernetes HPA and monitoring.
Configuration – Keeps port and other settings in MetastoreConf but bridges them into Spring (e.g., via system properties) so Spring Boot uses the configured port.
Graceful shutdown – Uses Spring Boot’s shutdown handling with a configurable timeout.
Standalone packaging – Adds a spring-boot-maven-plugin “exec” JAR for running the server as a standalone process.

Why are the changes needed?

Spring Boot improves how the Standalone REST Catalog Server is run and operated:

Kubernetes support – Liveness and readiness probes (/actuator/health/*) let Kubernetes reliably route traffic and restart unhealthy pods. Readiness includes an actual HMS connectivity check instead of a simple config check.
Observability – Prometheus metrics enable HPA, dashboards, and alerting, which is standard for production deployments.
Operational behavior – Graceful shutdown and a well-defined lifecycle reduce the chance of dropped requests during restarts.
Maintainability – Spring Boot replaces custom servlet wiring and configuration, and aligns with common patterns for cloud-native Java services.

Does this PR introduce any user-facing change?

If the standalone REST Catalog server is deployed in Kubernetes:

Liveness/readiness probes – Configure HTTP probes to use the new actuator endpoints:
-- Liveness: httpGet: /actuator/health/liveness
-- Readiness: httpGet: /actuator/health/readiness
Metrics/HPA – Prometheus scraping or custom metrics use /actuator/prometheus.

How was this patch tested?

Integration tests in TestStandaloneRESTCatalogServer and TestStandaloneRESTCatalogServerJwtAuth run the Spring Boot standalone HMS REST catalog server and verify liveness/readiness probes, Prometheus metrics, REST catalog operations, and JWT auth with Keycloak (Testcontainers).

deniskuzZ · 2026-02-20T14:29:22Z

	Suppressed: java.lang.NullPointerException: Cannot invoke "org.keycloak.admin.client.Keycloak.close()" because "this.keycloak" is null
		at org.apache.iceberg.rest.extension.OAuth2AuthorizationServer.stop(OAuth2AuthorizationServer.java:181)
		at org.apache.iceberg.rest.extension.HiveRESTCatalogServerExtension.afterAll(HiveRESTCatalogServerExtension.java:124)
		... 1 more
Caused by: java.lang.ClassNotFoundException: jakarta.annotation.Priority

deniskuzZ · 2026-02-20T14:39:22Z

-    LOG.info("=== Test: Health Check ===");
-    
-    String healthUrl = "http://localhost:" + restCatalogServer.getPort() + "/health";
+  public void testPrometheusMetrics() throws Exception {


do we use spring actuator? nice :)

deniskuzZ · 2026-02-20T14:48:53Z

to support OAuth / JWT Authentication don't we need SecurityConfig?

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.oauth2ResourceServer()
            .jwt(); // validate JWT tokens
    }
}

cc @okumin

deniskuzZ · 2026-03-10T11:44:17Z

+      System.setProperty(ConfVars.CATALOG_SERVLET_PORT.getVarname(), String.valueOf(port));
+    }
+
    StandaloneRESTCatalogServer server = new StandaloneRESTCatalogServer(conf);


Spring Boot should manage the lifecycle of your application class. Typically you don't manually instantiate your @SpringBootApplication class. see above snippet

deniskuzZ

added few comments, rest LGTM

deniskuzZ

LGTM +1

sonarqubecloud · 2026-03-13T08:44:48Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

difin requested a review from deniskuzZ February 19, 2026 15:54

asf-ci-hive added the tests pending label Feb 19, 2026

difin mentioned this pull request Feb 19, 2026

HIVE-29468: Standalone HMS REST Catalog Server: Migrate to Spring Boot #6324

Closed

asf-ci-hive added tests unstable and removed tests pending labels Feb 19, 2026

difin force-pushed the hms-standalone-rest-server-with-spring-boot branch from 2e24788 to 196fd31 Compare February 19, 2026 20:19

asf-ci-hive added tests pending tests unstable and removed tests unstable tests pending labels Feb 19, 2026